{
 "metadata": {
  "signature": "sha256:90b64f6899d24de768db6c652ab56e55f5b328e0ffa632241f1d4ca86ac9fd04"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Matplotlib: maps\n",
      "======================================================================\n",
      "\n",
      "Plotting data on map projections is easy with the basemap toolkit.\n",
      "Toolkits are collections of application-specific functions that extend\n",
      "matplotlib.\n",
      "\n",
      "**The basemap toolkit is not in the default matplotlib install** - you\n",
      "can download it from the matplotlib sourceforge [download\n",
      "page](http://sourceforge.net/project/showfiles.php?group_id=80706&package_id=142792).\n",
      "\n",
      "Suppose you'd like to make a map of the world using an orthographic, or\n",
      "satellite projection and plot some data on it. Here's how to make the\n",
      "map (using matplotlib \\>= 0.98.0 and basemap \\>= 0.99):"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from mpl_toolkits.basemap import Basemap\n",
      "import matplotlib.pyplot as plt\n",
      "import numpy as np\n",
      "# set up orthographic map projection with\n",
      "# perspective of satellite looking down at 50N, 100W.\n",
      "# use low resolution coastlines.\n",
      "# don't plot features that are smaller than 1000 square km.\n",
      "map = Basemap(projection='ortho', lat_0 = 50, lon_0 = -100,\n",
      "              resolution = 'l', area_thresh = 1000.)\n",
      "# draw coastlines, country boundaries, fill continents.\n",
      "map.drawcoastlines()\n",
      "map.drawcountries()\n",
      "map.fillcontinents(color = 'coral')\n",
      "# draw the edge of the map projection region (the projection limb)\n",
      "map.drawmapboundary()\n",
      "# draw lat/lon grid lines every 30 degrees.\n",
      "map.drawmeridians(np.arange(0, 360, 30))\n",
      "map.drawparallels(np.arange(-90, 90, 30))\n",
      "plt.show()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "There are many other map projections available, probably more than\n",
      "you've even heard of before. A complete list is available in the\n",
      "[basemap\n",
      "docstrings](http://matplotlib.sourceforge.net/mpl_toolkits.basemap.basemap.html).\n",
      "Coastlines, political boundaries and rivers are available in four\n",
      "resolutions, , , and . Here's what the resolution coastlines look like.\n",
      "\n",
      "![](files/attachments/Matplotlib_Maps/basemap0.png)\n",
      "\n",
      "Now, suppose you would like to plot the locations of five cities on this\n",
      "map. Add the following just before the in the above script:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# lat/lon coordinates of five cities.\n",
      "lats = [40.02, 32.73, 38.55, 48.25, 17.29]\n",
      "lons = [-105.16, -117.16, -77.00, -114.21, -88.10]\n",
      "cities=['Boulder, CO','San Diego, CA',\n",
      "        'Washington, DC','Whitefish, MT','Belize City, Belize']\n",
      "# compute the native map projection coordinates for cities.\n",
      "x,y = map(lons,lats)\n",
      "# plot filled circles at the locations of the cities.\n",
      "map.plot(x,y,'bo')\n",
      "# plot the names of those five cities.\n",
      "for name,xpt,ypt in zip(cities,x,y):\n",
      "    plt.text(xpt+50000,ypt+50000,name)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/Matplotlib_Maps/basemap1b.png)\n",
      "\n",
      "Calling a basemap class instance with arrays of longitudes and latitudes\n",
      "returns those locations in native map projection coordinates using the\n",
      "[proj4](http://proj.maptools.org) library. Now suppose you have some\n",
      "data on a regular latitude/longitude grid and you would like to plot\n",
      "contours of that data over the map. Try adding the following lines just\n",
      "before"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# make up some data on a regular lat/lon grid.\n",
      "nlats = 73; nlons = 145; delta = 2.*np.pi/(nlons-1)\n",
      "lats = (0.5*np.pi-delta*np.indices((nlats,nlons))[0,:,:])\n",
      "lons = (delta*np.indices((nlats,nlons))[1,:,:])\n",
      "wave = 0.75*(np.sin(2.*lats)**8*np.cos(4.*lons))\n",
      "mean = 0.5*np.cos(2.*lats)*((np.sin(2.*lats))**2 + 2.)\n",
      "# compute native map projection coordinates of lat/lon grid.\n",
      "x, y = map(lons*180./np.pi, lats*180./np.pi)\n",
      "# contour data over the map.\n",
      "CS = map.contour(x,y,wave+mean,15,linewidths=1.5)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/Matplotlib_Maps/basemap2b.png)\n",
      "\n",
      "Instead of plotting the continents and coastlines, you can use an image\n",
      "as a map background using the method. The default background image is\n",
      "the NASA 'blue marble' image, which you can apply by using"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "map.bluemarble()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "in place of"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "map.drawcoastlines()\n",
      "map.drawcountries()\n",
      "map.fillcontinents(color='coral')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Here's what the resulting plot looks like (using white text instead of black, and white dots instead of blue)\n",
      "\n",
      "![](files/attachments/Matplotlib_Maps/basemap3c.png)\n",
      "\n",
      "You can also plot images, pcolor plots and vectors over map projections.\n",
      "Examples that illustrate this and more can be found in the examples\n",
      "directory of the basemap source distribution."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}